MetonaAI-Desktop 架构与交互设计

# ~/MetonaWorkspaces/my-project/
├── SOUL.md          # [必需] AI 灵魂定义 — 角色、性格、核心价值观（用户自定义）
├── AGENTS.md        # [必需] AI 行为定义 — 规则、边界、工作流（用户自定义）
├── MEMORY.md        # [必需] AI 持久记忆 — 跨会话保留的知识（Agent 维护 + 用户编辑）
├── USERS.md         # [必需] 用户画像 — 背景、技能、偏好（用户自定义）
├── logs/              # [自动创建] 会话日志（每次对话一个 .jsonl）
├── traces/            # [自动创建] 执行追踪（每次 ReAct 迭代一条 trace）
├── .metona/           # [自动创建] Metona 内部目录
│   └── agent.db       # SQLite 数据库（配置、记忆、审计日志、会话记录）
└── src/               # [可选] 用户项目文件（Agent 可读写）

-- .metona/agent.db > app_config
CREATE TABLE app_config (
    key         TEXT PRIMARY KEY,
    value       TEXT NOT NULL,        -- JSON 格式值
    category    TEXT NOT NULL,        -- llm | agent | tools | security | logging | mcp
    updated_at  TEXT DEFAULT (datetime('now'))
);

-- 配置分类索引
CREATE INDEX idx_config_category ON app_config(category);

-- .metona/agent.db > mcp_servers
CREATE TABLE mcp_servers (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL UNIQUE,
    transport   TEXT CHECK(transport IN ('stdio', 'sse')),
    command     TEXT,                    -- stdio 模式的命令
    args        TEXT,                    -- JSON 数组格式的参数
    url         TEXT,                    -- SSE 模式的 URL
    enabled     BOOLEAN DEFAULT TRUE,
    created_at  TEXT DEFAULT (datetime('now')),
    updated_at  TEXT DEFAULT (datetime('now'))
);

# SOUL.md — 用户自定义 Agent 灵魂

## 身份
# 定义 Agent 是谁：名称、角色、核心特征

## 性格与语气
# 定义 Agent 如何与用户交流：风格、语气、态度

## 核心价值观
# 定义 Agent 的行为准则和底线

# AGENTS.md — 用户自定义行为规则

## 行为准则
# 定义 Agent 必须遵守的规则

## 工具使用规范
# 定义哪些工具可用、何时需要确认

## 安全边界
# 定义 Agent 的行为底线

## 工作流程
# 定义 Agent 的推理和执行流程

# MEMORY.md — AI 持久记忆
#
# 格式版本: 1.0
# 创建时间: 2026-06-25T12:00:00Z
# 最后更新: 2026-06-25T12:00:00Z
# 工作空间: /home/user/MetonaWorkspaces/my-project
#
# 此文件由 Metona Agent 自动维护，用户可手动编辑。
# 格式规范详见文档，Agent 写入时会自动校验格式。

## 用户偏好
# 格式: - [类别] 内容描述
# 示例: - [沟通风格] 用户喜欢简洁的回答

## 项目上下文
# 格式: - [项目名] 关键信息
# 示例: - [MyApp] 技术栈: React + TypeScript

## 重要决策
# 格式: - YYYY-MM-DD: 决策内容
# 示例: - 2026-06-25: 选择 sql.js 作为数据库方案

## 待办事项
# 格式: - [状态] 任务描述 (状态: pending/done/cancelled)
# 示例: - [pending] 实现用户登录功能

## 已知问题
# 格式: - 问题描述 | 影响范围 | 解决方案
# 示例: - 首次加载慢 | 启动 | 预加载优化

# MEMORY.md — AI 持久记忆
#
# 格式版本: 1.0
# 创建时间: 2026-06-25T12:00:00Z
# 最后更新: 2026-06-25T15:30:00Z
# 工作空间: /home/user/MetonaWorkspaces/my-project

## 用户偏好
- [沟通风格] 用户喜欢简洁的回答，不需要过度解释
- [代码风格] 代码块使用 TypeScript 语法高亮
- [工具偏好] 项目使用 pnpm 而非 npm

## 项目上下文
- [MetonaAI-Desktop] 技术栈: React 18 + Electron 28 + TypeScript 5.x
- [MetonaAI-Desktop] 构建工具: Vite + electron-builder

## 重要决策
- 2026-06-20: 选择 sql.js 作为 SQLite 实现
- 2026-06-22: 决定采用四层 Harness 架构

## 待办事项
- [pending] 实现 MCP Server 动态加载
- [done] 完成 Agent Loop 状态机

## 已知问题
- Windows 下 electron-builder 签名需要证书 | 部署 | 使用代码签名证书

# USERS.md — 用户自定义画像

## 基本信息
# 称呼、角色、经验等

## 技术栈
# 熟悉的技术、工具、框架

## 偏好
# 工具偏好、沟通风格、工作习惯

## 当前目标
# 正在做什么、想要达成什么

# logs/session_s_abc_20260625T120000Z.jsonl
{"seq":0,"ts":"2026-06-25T12:00:00.000Z","event":"session_start","sessionId":"s_abc","workspace":"/home/user/my-project"}
{"seq":1,"ts":"2026-06-25T12:00:01.000Z","event":"context_built","sessionId":"s_abc","tokens":1240,"ratio":0.01}
{"seq":2,"ts":"2026-06-25T12:00:01.500Z","event":"iteration_start","sessionId":"s_abc","iteration":1}
{"seq":3,"ts":"2026-06-25T12:00:02.100Z","event":"llm_request","sessionId":"s_abc","iteration":1,"provider":"deepseek","model":"deepseek-v4-pro","messages":[...]}
{"seq":4,"ts":"2026-06-25T12:00:03.800Z","event":"llm_response","sessionId":"s_abc","iteration":1,"content":"Thought: 需要读取文件...","finishReason":"tool_calls","usage":{"inputTokens":1240,"outputTokens":85,"totalTokens":1325}}
{"seq":5,"ts":"2026-06-25T12:00:03.810Z","event":"tool_call","sessionId":"s_abc","iteration":1,"tool":"read_file","args":{"file_path":"data.csv"}}
{"seq":6,"ts":"2026-06-25T12:00:03.820Z","event":"tool_result","sessionId":"s_abc","iteration":1,"tool":"read_file","success":true,"durationMs":5,"result":"..."}
{"seq":7,"ts":"2026-06-25T12:00:04.500Z","event":"iteration_end","sessionId":"s_abc","iteration":1,"durationMs":3000}
{"seq":8,"ts":"2026-06-25T12:00:10.000Z","event":"session_end","sessionId":"s_abc","totalIterations":3,"totalTokens":5430,"totalDurationMs":10000}

-- .metona/agent.db > audit_logs
CREATE TABLE audit_logs (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id  TEXT NOT NULL,         -- 会话 ID
    iteration   INTEGER,                 -- ReAct 迭代轮次
    event_type  TEXT NOT NULL,         -- tool_call | permission_check | error | llm_request | llm_response
    actor       TEXT NOT NULL,         -- 'agent' | 'user' | 'system'
    target      TEXT NOT NULL,         -- 操作对象 (工具名 / 模块名)
    details     TEXT,                    -- JSON 格式详细信息
    outcome     TEXT,                    -- 'success' | 'denied' | 'error'
    duration_ms INTEGER,                 -- 耗时
    created_at  TEXT DEFAULT (datetime('now'))
);